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REV ]} REVISION 
APPROVED BY ISIONS 


C | 3/9/82 Changes for the Mark 11.0 Release. 
Changed "'CANDE/WORK.FILE" to "'CANDE/WORK-FILE" throughout 
document. 


l-1 Changed “B1700" to “B1000" in first paragraph. 


OTHE INFORMATION CONTAINED IN THIS DOCUMENT 1S CONFIDENTIAL AND PROPRIETARY TO BURROUGHS 
CORPORATION AND (§ NOT TO BE DISCLOSED TO ANYONE OUTSIDE OF BURROUGHS CORPORATION wiTHOUT 
THE PRIOR WRITTEN RELEASE FROM THE PATENT DIVISION OF BURROUGHS CORPORATION’ 


SRP 1968 A.96 


sie ap so ide ties gg Senay ipe Sgred see a eg iD Le Rate Beier SES Leo Sa St a ee EES Bees oa 


| | : 7 | 2219 0185 
Burroughs Corporation <3) B1800/B1700 CANDE/ANALYZER 


COMPUTER SYSTEMS GROUP 
SANTA BARBARA PLANT 


PRODUCT SPECIFICATION 


REV | REVISION PPROVED B iSIONS 
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, | Original Issue - Release level MARK 6.1 


yA eiaawes for the MARK VIII. 0 Release 


Throughout | Delete all references to CANDE/TANK. FILE 

/ 1-2 Add paragraph on running ANALYZER without 
a CANDE/AUDIT file. 

3-1 Add PROGRAM. SWETCH(1) 

3-1 to 

3-3 Change default PROGRAM, SWITCHES meanings 

3=3 Add PROGRAM. SWITCH(%) 

3-4 Add CONSOLE, SWITCH(1) 
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GENERAL 

INTRODUCTION 


CANDE/ANALYZER is a companion program to 681000 CANDE and is 
intended primarily to aid in debugging CANDE. In an interactive 
real-tise program such as CANDE» bugs can exist which b6ecome 
evident only upon entering some unusual sequence of coaumands or 
which involve a particular interaction between two or more users. 
When such bugs occurs it is typicatly difficult or ispossible for 
users to know precisely what they did that caused the CANDE 
failure. CANDE/ANALYZER should help resotve this problen. 


Two principles guide the :analysis process: 


Since bugs are the exception rather than the rule» the perform- 
ance of CANDE should not be noticeably affected by the added 
function of maintaining a trace file. 


When an anatysis is requirede information should be provided 
which is as complete and readable as possible. It is not 
possible to know in advance what information wilt be useful in 
tracking down bugs. , 
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ANALYZERZAUCITEILE INTERFACE 


At BOJ» CANDE creates a trace fite called CANDE/AUDIT and writes 
information about each USER/CANDE transaction into that file. 
CANDE/AUDIT is laid out to minimize the time required to create 
the trace and is not easily read by the user. CANDE/ANALYZER» 
then» assumes the burden of reading the audit file and of 
breaking it down into a format easily read by the user. 


The analyzer generates two general types of information: 


le An analysis of the information included in CANDE/WORK- 
FILE and CANDE/RECOVERY. 


2s A trace of alt messages sent to and received by CANDE» 
excluding messages transmitted or recieved during any 
time that CANDE was instructed to stop auditing 
messageSe 


CANDE/ ANALYZER “wilt run even when the second type of information 
(message trace) was not maintained by CANDE or is unavailable. 
However» if the CANDE/AUDIT file is presents» it is also printed. 


RELATED DOCUMENTATION 


Name CRev) Nuaber 
CANDE | P.S-e 2212 5561 
DC/AUDIT P.S.- 2212 5421 


Bi700 Software Operationat Guide 1068731 
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STRUCTURE OF AUDIT EXILE 


The audit file» catted CANDE/AUDIT» is created at BOJ if CANDE 
finds that there are at least 720 bytes of dynamic CANOE memory 
avaitable>» i ele» enough for alt of the audit buffers. Ail 
messages which go through the file MCSQUEVUE are written to the 
audit file>» a circular buffer of 999 records» each with 360 
bytes. The first record in the file is cathed the Audit 
Parameter Block CAPB) and is initialized by CANDE at BOJ to 
contain inforrgation about CANDE itself: compite date and times 


job number» etc. The remaining 999 records constitute the 
circular buffer in which CANDE packs as many as fifteen messages 
per record. The first four bytes of each record describe the 


contents of that record. 


AUDIT RECORD 


The audit record is described as follows: 
The first four bytes of each disk record are declared as: 


OL AUDIT.~FIRST.FOUR-BYTES BITC32)» 
| O2 AUDIT.BUFF.COUNT BITC15)>» 
O2 AUDIT-BUFF OFFSET BITC 9)» 
O02 AUDIT.SUFF.MESSAGES BITC8)>s 


AUDIT BUFF .COUNT is bumped by CANDE each time it writes a new 
disk records thus providing a way for the analyzer to determine 
which record was the last one written. Note that this fieid must 
be able to hold a number Larger than the nuaber of records in the 
disk file in order to guarantee that the counter cannot wrap 
around sore than once in one pass through the file. 


AUDIT.BUFF .OFFSET is the byte address» relative to the first byte 
of the current records where the first complete message begins in 
this record. This information is used by the analyzers when it 
finds the head of the queue» to determine where in the record to 
begin its analysis. 


AUDIT.~BUFF MESSAGES indicates the nusber of messages which 
actuattly BEGIN in the current record and is used by the analyzer 
to search “backwards” through the file tin order to print the last 
<n> messages specified by the user. For example» the user might 
request that only the Last 100 messages be printed. The analyzer 
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can quickly deterrmine how many records sust be examined in order 
to analyze only the last 100 messages. 


Each message is structured as follows: 


OL AUDIT.MESSAGE 


O02 AUDIT.TYPE BIT(8)>» 

O02 TIME.STAMP BITC20)> 

02 FILLER BITC4)» 

O02 AUDIT.HEADER BITC126)» 

02 FILLER BIT(2)» 

02 TEXT.LENGTH FIXED» 

O02 AUDIT.TEXT CHARCTEXT LENGTH)3 


AUDIT.TYPE indicates the type of this sessage. For example» a 
request for permission to open a files text sent from aiusers ~or 
text sent from CANDE to a user. 


TIMESTAMP is the variable SYSTEM.TIME in CANDE and is the value 
obtained from the SDL construct TIMECCOUNTER>SBIT ). 


AUDIT.HEADER is the NDL MESSAGE.HEADER from the current message 
being sent to or coming from a user. Note that this field ts the 
bit representation of the header» not the character version. 
This field is atways included in each messager» although it would 
be possible to have some AUDIT.TYPE fields which did not include 
it. The analyzer could be modified to handle this. 


TEXTe-SIZE is the nusber of characters which follow tin this 
message and may be zero. Note that it is entirely possible for 
this number to be smattler than the MESSAGE.-SIZE field in the 
MESSAGE-HEADER because messages in the audit fite witt have 
trailing blanks crunched off. In additions some audit messages 
Ce.ge» PAGE mode messages) only include the sequence fields» not 
all of the user®s text. 


AUDIT-TEXT is the actual text being sent to or coming from the 
user « 


FILLER items are used to pad entries to byte boundaries and to 
force each record to be an integer number of bytes in length. 


Notes 6-1 CANDE wilt delete traiting blanks on all outputs to 
TD800/802» TD820/822» 10830/832» and TD700 terminais. 
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OPTIONAL FEATURES 


Optional features assoctated with the CANDE/ANALYZER program are 
set through PROGRAM.SWITCH options. Default (zero) settings mean 
that the program analyzes the USER-eRESIDENT areas for tlogged on 
LSNs only» prints the entire trace audit» and does not ZIP 
execute CANDE after analyzing CANDE*’s work and recovery files. 
It wili not remove the audit file after analyzing it. The 
default program switch settings of zero provide as much usefui 
information as possible. 


PROGRAM SWITCH SETTINGS 


Program switches are defined as follows: 


PROGRAM: SHITCH(O) 
Zero - Print only those LSNs which have the 
LOGGED-.ON bit in the USER-.-RESIDENT.AREA 
true. 


“Non-zero = Print all LSNs. 


PROGRAM SWITCH(A) 


Zero - Analyze the CANDE files CANDE/WORK-FILE and 
CANDE/RECOVERY even though the CANDE/SAUDIT 
file is not present. 


Non-zero = Do not attenpt the analysis of any CANDE files 
if the CANDE/AUDIT file is not present. 


PROGRAM2SWITCHC2) 


zero - Print trace audit. 


Non@zero = Do not print trace audite 
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PROGRAM.-SWITCH(3) 
Zero - Print analysis of the USER.RESIDENT 


areas for the various LSNs. 


Non-zero - Do not print USER-RESIDENT areas. 


PROGRAM: SWITCHES) 


Zero - When printing the USER.»RESIDENT areas» 
include printing of the workfile contents 
for each users 


Non@zero = When printing the USER-RESIDENT areas» 
do not print the contents of the workfile. 


PROGRAMeSWITCHCS) 


Zero - Print the entire trace. 

One - Print only the final 500 entries of trace. 

2°15 - Print only the final 100 entries of trace. 
PROGRAM sSWITCHC6) 

Zero - Do not ZIP execute CANDE after using 


CANDE*s work and recovery fites. 


Non-zero = ZIP execute CANDE after using CANDE®S 
work and recovery files. 


PROGRAM sSWITCHC7) 
Zero - Do not remove the audit file after analyzing 
| it. 


Non-zero = Remove the audit file after analyzing it if there 
| are no other users of it. 
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PROGRAM: SWIICHC8) 
Zero - Print information in CANDE/WORK“FILE» and 


CANDE/RECOVERY even when these files are atready 
in usee This means that the information printed 
may be of questionable integrity since CANDE may 
be chaning it interspersed with the analyzer 's 
accessing ite 


Non-zero = Do not print information in CANDE/WORK*FILE or 
CANDE/RECOVERY when these files are tin use (Cor 
Bissings obviously). 


PROGRAMsSWITCHC9) 


Zero - Print the entire fine table for each users 
workfile. (The rough tabte for each users 
workfile is always printed.) 


Non-zero = Do not print each users fine table for the 
corresponding workfile. 


CONSOLE SWITCH SETTINGS 


CANDE/ANALYZER also contains runctime optionss through console 
Switch settingse Note: in order to use console switch options» 
the option must be set through the "SE* SPQ command (See MCP 
CONTROL SYNTAX» PeSe 2219 0144 for a discussion of SE). 
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CONSOLE-SWITCHCO) 
Zero = Print each user*s workfile in its entirety. 
Non-zero = Stop printing the current workfile. This option 
is included to bypass the printing of a particular 
user*®s workfile Ceven after the printing has begun) 
when that workfile is lengthy and is no Conger of 
interest for analysis. The user Coperator) should 
reset the switch after the printing of the current 
workfile stops so that the next user’*®s workfile 
is printed norawatly. Leaving the switch set will 
inhibit the printing of the contents of all remaining 
workfiles. | 
CONSOLES RITOCH CID 
Zero - Print each user's fine table in its entirety. 
Non-zero ~ Stop printing the current fine tabte. (See 


additional comments under COQONSOLE-.SWITCHCO)> 
above.) 
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